5.5 The Batch Directory Synchronization Tool

MyID can be configured to update user information in MyID from the LDAP directory automatically when a user record is selected. This tool does the same thing for all accounts in MyID.

The Batch Directory Synchronization Tool is used to synchronize users imported into MyID with the latest information held in the directory. If MyID is integrated with multiple LDAP directories, all the directories will be included in the synchronization process.

You run the tool on the MyID application server, under the MyID COM user. You can run the tool from the Start menu, from the command line or as a scheduled task. For an installation containing a significant number of records, Intercede recommends that you run the synchronization tool as a scheduled task.

5.5.1 Configuring the Synchronization Tool for load sharing

Where multiple application servers are available, you can configure the Synchronization Tool to spread processing load over these servers.

Where load sharing is required, the records processed by each application server are specified by providing the range of records to be processed using start and end percentile range values.

To ensure that all records are processed by the servers, the specified percentile ranges must cover the full percentile range from 0 to 100%; for example, a simple split with two application servers may be:

• Server 1: 0 – 50%

• Server 2: 51 – 100%

To ensure that all the records are processed, the Synchronization Tool will process all records up to the top of the percentile range.

Important: Use of load sharing is enabled only when the whenChanged option has not been selected

5.5.2 How does the Synchronization Tool work?

The Synchronization Tool processes all the records in the MyID database that are mapped to entries in an LDAP directory.

• If the record exists in MyID but the corresponding entry is no longer present in the LDAP directory, the tool can disable the user account and revoke the associated certificates.

• If the record exists in both MyID and the LDAP directory, any changes to the information held in the LDAP directory are copied to MyID.

  If the user account has been disabled in Active Directory, the user account in MyID can also be disabled and associated certificates suspended – you must set the Disable on removal from directory configuration option.

  Note: You can choose to revoke certificates instead of suspending them if the user account is suspended in the directory. Please contact customer support for details.

  Note: When you synchronize the records, if you have changed information in MyID, but not copied these changes to the directory, the changes will be overwritten by the information from the directory.

• If the whenChanged option is selected (either by selecting the whenChanged checkbox on the tool window, or by specifying the -whenchanged option on the command line) the tool processes only those records that have been updated since the last time the tool was run. The whenChanged attribute in the directory is used to identify these records. The date and time of start of the last run of the tool is stored in the MyID database.

• If the Start range is specified, the first record processed will be at the start of the specified percentile. By default, this is 0%, which processes the records from the beginning.

• If the End range is specified, the last record to be processed will be at the top of the specified percentile range. By default, this is 100%, which processes up to the last record.

• If the record exists in MyID, but the corresponding entry is no longer present in the directory, the behavior of the tool depends on whether the whenChanged option is selected:
• If the whenChanged option is selected, the tool will not update the MyID database to reflect the removal of the user from the directory. In this case, you must use the Active Directory Deletion Tool to synchronize the deleted users. See section 5.8, The Active Directory Deletion Tool for details.

• If the whenChanged option is not selected, the tool can disable the user account and revoke the associated certificates. This depends on whether the following options have been selected on the LDAP page of Operation Settings workflow in the Configuration category:

  • Disable on removal from directory.
  • Revoke certificates if user is removed or disabled following background directory update.

Note: When the tool is run for the first time since installation or upgrade, it runs without the whenChanged behavior, whatever options you select; this is to provide an initial successful run to set the start time of the last successful run in the database. If you select the whenChanged option, the tool displays a warning:

All changes are written directly to the MyID database and are fully audited.

5.5.3 Revoking certificates

The behavior of MyID in revoking certificates for users who have been removed from the directory depends on the combination of MyID configuration options:

Disable on removal from directory	Revoke certificates if user is removed or disabled	Behavior
NO	NO	User in MyID is unaffected.
NO	YES	User in MyID is unaffected.
YES	NO	User is disabled in MyID. Associated certificates are unaffected.
YES	YES	User is disabled in MyID and associated certificates are revoked.

5.5.4 Running the tool from the Start menu

By default, the tool runs in interactive mode from the Start menu. You can change this by editing the properties of the shortcut to incorporate the flags specified in section 5.5.5, Running the tool from the command line.

Note: Run the utility under the MyID COM user account.

A summary of the records processed and the time taken is displayed on completion of the synchronization process.

Checked against LDAP 12242, Updated 9191 ( removed from LDAP(2), disabled in LDAP(3) )

This means that the tool carried out the following:

• Parsed 12242 user records.

• Updated 9191 users with changes from the LDAP synchronized to MyID. This includes users removed or disabled in the LDAP.

Note: If the Disable on removal from directory option on the LDAP page of the Operation Settings workflow is set, the users removed from the LDAP and the users disabled in the LDAP will also be disabled in MyID.

5.5.4.1 Running the tool with the whenChanged option

1. From the Start menu, run the Batch Directory Synchronization Tool.
2. To update only those records that have been changed since the last time the Batch Directory Synchronization Tool was run, select the whenChanged option.

3. Click Synchronise.

   

   Progress is displayed both in the text area and in a progress bar towards the bottom of the dialog.

5.5.4.2 Running the tool by specifying a processing range

1. From the Start menu, run the Batch Directory Synchronization Tool.

2. Specify the Start range and End range to be processed by the tool.

3. Do not select the whenChanged option.

4. Click Synchronise.

   

   Progress is displayed both in the text area and in a progress bar towards the bottom of the dialog.

   The output displays the user ID range that is processed by the synchronization process.

   Processing user ID range: 4 – 12251

   When checking each user ID in the above range, the user ID is first checked in MyID to determine if:

   • The user ID is associated with a user.

   • The user is an LDAP user. This is determined by checking that the user has a DN and is marked as linked to an LDAP external server.

   No further processing is required on any user ID that does not satisfy the criteria for being a valid LDAP user record within MyID; otherwise, the user data is compared against the corresponding user LDAP data. An update action, and audit, is performed as a result of this comparison if:

   • The user has been disabled in LDAP but is enabled in MyID.

   • The user is enabled in LDAP but disabled in MyID.

   • The user is not found in LDAP.

   • The checked user data does not match.

   No update is required otherwise.

   On completion, a summary of the action taken on the LDAP user records is provided; for example:

   Checked against LDAP 12242, Updated 9191 ( removed from LDAP(2), disabled in LDAP(3) )

   In this example:

   • 12242 LDAP records where checked.

   • Of these, 9191 records met one or more of the criteria requiring an update. This count includes:

   • Users who have been removed from LDAP. Set to 2 in the above example.

   • The users who were found to be disabled in LDAP. Set to 3 in the above example.

   A breakdown summary of the split in the processing time between updated and not updated records is also provided on completion:

   Updated records 9191, Check and update time: 1636s, Audit time: 215s

   Records not updated: 3051, Check time: 281s, Audit time: 0s

   This means that:

   • 9191 records required some sort of update, either to synchronize the LDAP change, or to remove or disable/enable a user.

   • The total time spent on checking and updating these records was 1636 seconds.

   • The total time spent on adding audit information for these records was 215 seconds.

   • 3051 records were found to not require any update. The total time spent on processing these records is 281 seconds.

   An intermediate summary of the records processed is provided every 5% percentile range:

   Percentile records information: Range 0 – 5% Updated 2046 Not Updated 3051 records

5.5.5 Running the tool from the command line

Note: Run the utility under the MyID COM user account.

You can run the Batch Directory Synchronization Tool from the command line using the following command lines:

• Interactively – run BatchLDAPSync.exe without specifying the -silent or -autorun flags. The tool runs as described in section 5.5.4, Running the tool from the Start menu.
• Automatic execution – run the program with the -autorun flag. The dialog is displayed as described in section 5.5.4, Running the tool from the Start menu, the synchronization process starts automatically, and the dialog closes when the process has finished.
• Silently – run the program with the -silent flag. This works in the same way as ‑autorun but the dialog is not displayed. (Do not use both -silent and -autorun at the same time.)
• New changes only – run the program with the -whenchanged flag. Only those records that have been changed since the last time the Batch Directory Synchronization Tool was run are updated.

• Range of records – for splitting the load, run the program with the -startrangepercentile and -endrangepercentile parameters. If you do not specify these parameters, the default values are 0 and 100 respectively. For example:

  -startrangepercentile 10 -endrangepercentile 20

  The percentile range setting is ignored if the -whenchanged option is set.

The case of the command-line options is not important. You can also use the first two letters of the command-line options instead of the full name; for example:

-st 10 -en 20

instead of:

-startrangepercentile 10 -endrangepercentile 20

If the tool detects an error in the command-line options, it displays a help dialog. This does not appear if you are using -silent or -autorun.

To record the details of the process to a specified file, including any command-line processing errors, add the -trace flag to the command. You can use this flag either alone or with the other flags. For example, you could run:

BatchLDAPSync.exe -silent -whenchanged -trace LDAPSync.log

If you do not specify a filename, batchldap.log in the current folder is used. The MyID COM+ user must have permission on this folder to create and write to the trace file.

Note: You are recommended to use the -trace option when running in -silent mode.

5.5.6 Running as a scheduled task

You can run the Batch Directory Synchronization Tool as scheduled task using standard Windows functionality.

The program to be run is called BatchLDAPSync.exe and the flags available are described in section 5.5.4, Running the tool from the Start menu.

5.5.7 Troubleshooting

• Unable to communicate with server

  If the Batch Directory Synchronization Tool experiences an error communicating with an LDAP server, it displays an error similar to:

  Checking External Server ID 2
  Error communicating with LDAP server, aborting

  This means that the tool has been unable to communicate with that particular server. Run the tool again once you have confirmed that the network is working correctly.

  Note: If you are running the tool in -silent mode, you will see this message only if you enable the -trace option and check the log after running the tool.

• Inaccurate totals when running multiple instances

  If you are running multiple instances of the Batch Directory Synchronization Tool concurrently, the total of updated users across all instances may not match the actual total of updated users – this is because the same update may be counted by more than one instance. The updates themselves are processed correctly; only the total is inaccurate.

• Time and date discrepancies

  The tool displays local time, while the database stores UTC time; this may lead to a perception of a discrepancy between the times and dates displayed.

• Error during first run

  If an error is encountered during the first attempted synchronization the database timestamp will not be updated. The next time you run the tool, it defaults to the non-whenChanged behavior. The following warning is displayed:

  

  If this occurs, you can:

  • Shut down the tool and restart it later to perform a synchronization when the problem has been resolved, or:
  • Allow the tool to attempt to synchronize the remaining users. The timestamp will not be updated, so all users changed since the previous run will have to be processed again the next time you run the tool.

• First run with -silent and -whenchanged options

  There is no need to specify -whenchanged on the first run; you are also recommended not to use -silent on the first run so that you can see the feedback from the tool on what has been processed.

• No valid user accounts detected

  If there are no users that require synchronization, and you do not have the whenChanged option selected, the tool displays a message similar to:

  Invalid user account IDs

  This means that there are no valid user account IDs to synchronize.

• Permissions errors

  If you attempt to run the utility under a user other than the MyID COM user, you may see errors similar to the following:

  Error occurred: 80070005

  or:

  Error occurred: 80004003

  Exit the utility, then log in as the MyID COM user, and run the utility again.